Hello, ScrivQ!

1 Instalation

To use ScrivQ24, you need the Quarto open-source scientific and technical publishing system.

Quickstart

On macOS¹, use Homebrew to brew install quarto && brew install chromium.
On Windows, use Chocolatey to choco install quarto.

After that, install TinyTex with quarto install tool tinytex.

¹ If you’re on a Mac, install Homebrew by pasting the following on the Terminal: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)".

New to Quarto?

Visit the get started guide to download.
Check the tutorial to learn how to create, build, and preview documents.
Install the Quarto extension for VS Code and R Studio.
Find out more at Awesome Quarto, Quarto Extensions, Quarto on Github, RStudio Community, Stack Overflow, Twitter.
See also the Pandoc User’s Guide, Pandoc-Discuss, and Pandoc at Stack Overflow.

Installation issues

Run a quarto check on your installation.

Some Python and R computations will require additional packages (cf. Warning 1).

Warning 1: Dependencies for computations

To run R computations, install R, R Studio, and (at least) the following packages:

py_install(packages = "matplotlib")
install.packages("reticulate")
install.packages("markdown")
install.packages("tidyverse")
install.packages("kableExtra")
install.packages("downlit")
install.packages("xml2")

Listing 1: Additional R packages.

2 ScrivQ

The ScrivQ template is designed to compile Quarto Books (PDF², DOCX, and HTML) with zero configuration and no dependencies on external files. The bibliography, the template files, extensions, and filters are all included in the project and will be created by the compiler script.

² Please note that tinytex is also required for LaTeX to PDF output.

When Quarto is installed…

Hit Cmd + Opt + E to publish your Quarto Book right away.

ScrivQ

Download the latest release.
Sponsor this project.
Take part in the discussion at the Scrivener forum.

Thank you

@iandol for the exceptional Scrivomatic from which ScrivQ descended.

Check his writing in Scrivener tutorial, if you haven’t done so yet.

3 Compiler Script

Figure 1: There is a ruby script to reformat the text and create the dependencies. It allows you to pass a file name and a format, so you can edit the post-processing panel to change the output format (*e.g.* change `html` to `pdf` / `docx` / `epub` etc.). It is embedded in this project’s Compiler format.

The script’s output is redirected &> to a Quarto.log file that will be automatically opened when an error happens and no output is produced. If everything runs smoothly, however, you should see only the output file open.

This compiler script descends from Scrivomatic, but with several changes to allow splitting the final document into sub-files. This task entails some challenges as footnotes and image references must be moved around before the file is split. Check the compiler script to see how this got solved and please report any errors.

Warning

Ruby must be installed on Windows machines.

4 Citations

Μῆνιν ἄειδε, θεά, Πηληιάδεω Ἀχιλῆος (Hom Il, I 1) The wrath sing, goddess, of Peleus’ son Achilles.

In ScrivQ, we use Citeproc to handle the bibliography and provide consistent output across different formats. Given Citeproc’s lack of features beloved by BibTeX users, we included Cite Tools to enable multipart bibliographies, provide backlinks (see backref from HyperRef), and access bibliographic data from sources (author, editor, translator, date, edition, number, and so on).

Official documentation

The official documentation on citations can be found at Pandoc and Quarto.

Cite Tools and ScrivQ

Deleting Cite Tools might cause the compilation to fail.

Using Cite Tools in other projects

quarto install extension bcdavasconcelos/citetools.

4.1 Basic citations

The citation syntax is straightforward: @Citekey for Author (Date) (an in-text citation); [@Citekey] for Author, Date; and [-@Citekey] for Date.
The citation key is optionally followed by a locator, which can be a page number, a line number, a chapter number, or a section number, preceded by a comma, e.g. [@Citekey, p.10].
Multiple citations can be grouped in brackets separated by semicolons [@CitekeyA; @CitekeyB]. The CSL style used by Citeproc will determine the presence (or absence) of parenthesis around the rendered citation. (We favor a style that doesn’t use parenthesis, but that is up to you.)

Character Style	Markdown Source	Rendered output³
Cite*	`[-@Long2004]`	2004
Cite*	`[-@Long2004, p.15]`	2004, p. 15
Cite	`[@Long2004]`	LONG, 2004
Cite	`[@Long2004, p.15]`	LONG, 2004, p. 15

³ The rendered citation will appear only in the output document; but not in the Scrivener project.

Table 1: Citation syntax in Quarto and Pandoc.

Here is a short demonstration of the basic citation feature. We suggest grouping the citations using parenthesis and using character styles to apply the correct markup. If you were using other CSL styles, then you could drop the parenthesis.

(Date, locator)

Long thinks […] on the deliberations of the prudent person (2004, p. 17).

(Author, Date, locator)

…on the deliberations of the prudent person (LONG, 2004, p. 17).

(Author, Date, locator; Author, Date, locator)

…on the deliberations of the prudent person (LONG, 2004, p. 17; HOFFMAN & PRAKASH, 2014, p. 15).

4.2 Citation of specific fields

To inject the correct markup – [@Citekey]{.csl_field} – and allow us to cite different fields from our bibliographic entry, we rely on Character Styles (e.g. Cite Author, Cite Editor, Cite Issued, and so on).

Officially, CSL has Variables, BibTeX has Fields, and RIS has Tags, but we stuck to the term fields to describe all of them.

Character Style	Markdown Source	Rendered Output
Cite Author	`[@DA]{.author}`	Aristotelis
Cite Editor	`[@DA]{.editor}`	Bekker
Cite Translator	`[@DA]{.translator}`	Τατάκης
Cite Issued	`[@DA]{.issued}`	1834
Cite Title	`[@DA]{.title}`	De Anima
Cite Title-short	`[@DA]{.title-short}`	De An.
Cite Original-title	`[@DA]{.original-title}`	περὶ ψυχῆς
Cite Publisher	`[@DA]{.publisher}`	Reimer
Cite Publisher-Place	`[@DA]{.publisher-place}`	Berlin

Table 2: All ready-made Character Styles for the Cite Field lua filter.

An example with field citation

Bekker published the first modern edition of Aristotle’s περὶ ψυχῆς (De Anima) in 1834. A new edition by Biehl appeared in 1896 (later reprinted in Theiler’s 1995 translation).

4.3 Multipart Bibliography

Where do I plug my bibliography?

There is no need to keep separate bibliography files in the system. Simply copy and paste the references directly to Scrivener following the instructions below.

References format

Pandoc and Quarto use a CSL (Citation Style Language) engine and prefer CSL-YAML and CSL-JSON (performing up to 10x faster) over BibTeX and RIS, which need to be converted before they can be understood.

What if I don’t have a bibliography ready?

Check Zotero ⁴ and JabRef on all platforms.
On macOS, check Bookends and Bibdesk;
See also this comparison.

⁴ Zotero even offers an API to download shared libraries by merely accessing a link, such as https://api.zotero.org/groups/LibraryID/items?format=bibtex&limit=999 where LibraryID corresponds to the library’s 7-digit code (visible in the middle of the library URL).

[BibTeX]: [CSL]: https://docs.citationstyles.org/en/stable/specification.html#appendix-iii-types [CSL-YAML]: https://docs.citationstyles.org/en/stable/specification.html [CSL-JSON]: https://docs.citationstyles.org/en/stable/specification.html [RIS]: https://en.wikipedia.org/wiki/RIS_(file_format)#Type_of_reference

4.3.1 How to manually create a multipart bibliography

Using the Section Type File, we create a representation of our bibliography file to add the data (e.g. Primary Sources and Secondary Sources).
On the Metadata panel we set the relative path (ID-Prefix + ID) and the extension (Extension) of the actual bibliography file that will be created upon Compile.

We need to tell Quarto about the bibliography file by adding it to the _quarto configuration file (there is a bibliography section), then we can print the formatted bibliography using the ID (e.g. “primary-sources”) with the Paragraph Style Div Bibliography.

ARISTOTELIS. “De Anima.” In: BEKKER, I. (Ed.). Aristotelis Opera. Tran.: Β. Τατάκης. Berlin: Reimer, 1834. [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]

HOMERUS. “Ilias.” In: ALLEN, T. W. (Ed.). Homeri Ilias, vols. 2–3. Oxford: Clarendon, 1931. p. 2·1-356; 3·1-370. [1]

4.3.2 How to automatically create a multipart bibliography

We can use the Section Type Bibliography to automate steps 3 and 4. This is very convenient for books that need the bibliography to print only once at the very end.

Using the Section Type File, we create a representation of our bibliography file to add the data (e.g. Primary Sources and Secondary Sources).
On the Metadata panel we set the relative path (ID-Prefix + ID) and the extension (Extension) of the actual bibliography file that will be created upon Compile.
The metadata with the file path will be automatically added and the formatted bibliography will be printed in the same section as the data, with the same section title.

4.4 Backlinks

In Citeproc, link-citations control whether citations in the body of the text should be clickable links to the reference in the bibliography. Cite Tools takes it further and adds a backlink to each citation an entry has received in the document in a crescent ordinal fashion⁵. This allows the reader to easily arrive at sections of the text where the same reference was discussed and quickly see how many times each reference was used with the array of backlinks.

⁵ The reader will see the page number instead of a crescent ordinal number in some output formats, such as PDF.

Figure 3: The **Citation Backlinks** filter adds an index of cited references to the bibliography, with links back to all in-text citations. It also allows the user to turn these off globally or in an *ad hoc* fashion.

Citing specific fields

Turn link-fields into false to avoid undesired linking

Bibliography links

link-citations: Hyperlink citations to the corresponding bibliography entries. Defaults to true.
link-fields: Hyperlink citations targeting specific CSL fields to the corresponding entries in the bibliography. Defaults to true.
link-bibliography: Hyperlink DOIs, PMCIDs, PMID, and URLs in bibliographies. Defaults to true.
lang: Affects the bibliography tags. Defaults to en-US.

5 Quarto

“I propose a toast, to my self-control. You see it helpless, crawling on the floor.” Morphine, Cure For Pain (1993)

5.1 Scrivener Project Templates

All sorts of internal Scrivener Templates have been included for convenience. They serve as starting points to create new sections. Click Project > New From Template and select the desired Section Types from the list, which includes Bibliography, Code, Computation, Diagram Dot, Diagram Mermaid, Div, Equation, File, Metadata, Section, Text, Text (Anchored)⁶.

⁶ Text section with ID for cross-referencing.

This provides a huge number of options as the metadata can be edited to allow the creation of different Quarto elements and their customization (e.g. using classes and attributes). Using the Section Type Div, for example, one could create 8 different Amsthm elements, 5 different Callouts, and several Column environments. Using the Computation, one can create executable code blocks with R, Python, and Ruby. The Section Type Section can be numbered, unnumbered, or part of the appendix (with the use of classes).

Look at the ready-made examples to see what else is possible.

5.2 Cross-referencing

When creating a Section, select the correct ID-Prefix (e.g. sec-) and fill the ID metadata field with a value (e.g. xref). Then, use Scrivener placeholders ( <\$Custom:ID-Prefix><\$Custom:ID>) with a link to the cited element, so that this gets replaced with sec-xref. This works regardless of the element being cross-referenced (e.g. section, table, figure, listing) because this strategy ensures the citation will use the <\$Custom:ID-Prefix> pulled from the targeted element (e.g. sec-, tbl-, fig-, lst-), making it compatible with all element types.

Alternative to placeholders

A less verbose option uses a replacement rule:

s\crivlink is replaced with <\$Custom:ID-Prefix><\$Custom:ID>.
s\crivpath and $\! are replaced with <\$Custom:ID-Prefix><\$Custom:ID><\$Custom:Extension>.

How to cross-reference an element

Type your-keyword-of-choice or s\crivlink;
Apply the Character Style Cite (hit Shift + Command + Y)
Link to the document that contains the element (hit Command + L).

Known limitation

Understand that Scrivener Placeholders can only pull information from the section properties, so the generic link label (e.g. s\crivlink) will work to reference elements created from Section Types.

To reference elements created from Raw Markup or Character Style, use the actual ID given (e.g. fig-ulysses).

5.3 Amsthm

Species	Markdown Source	Rendered Output
Conjecture	`[@cnj-demo]`	Conjecture 1
Corollary	`[@cor-demo]`	Corollary 1
Definition	`[@def-demo]`	Definition 1
Example	`[@exm-demo]`	Example 1
Exercise	`[@exr-demo]`	Exercise 1
Lemma	`[@lem-demo]`	Lemma 1
Proposition	`[@prp-demo]`	Proposition 1
Theorem	`[@thm-demo]`	Theorem 1

Table 3: Cross-referencing Amsthm elements in ScrivQ.

Conjecture 1 Demonstration of the Conjecture theorem environment using the Section Type Div with ID #cnj-demo.

Corollary 1 Demonstration of the Corollary theorem environment using the Section Type Div with ID #cor-demo.

Definition 1 Demonstration of the Definition theorem environment using the Section Type Div with ID #def-demo.

Example 1 Demonstration of the Example theorem environment using the Section Type Div with ID #exm-demo.

Exercise 1 Demonstration of the Exercise theorem environment using the Section Type Div with ID #exr-demo.

Lemma 1 Demonstration of the Lemma theorem environment using the Section Type Div with ID #lem-demo.

Proposition 1 Demonstration of the Proposition theorem environment using the Section Type Div with ID #prp-demo.

Theorem 1 Demonstration of the Theorem theorem environment using the Section Type Div with ID #thm-demo.

\[[ x^2 + y^2 = z^2 ]\]

5.4 Callouts

Species	Markdown Source	Rendered Output
Caution	`[@cau-caution]`	Caution 1
Important	`[@imp-important]`	Important 1
Note	`[@nte-note]`	Note 1
Tip	`[@tip-tip]`	Tip 1
Warning	`[@wrn-warning]`	Warning 2

Table 4: Cross-referencing callouts.

Using styles, you can create normal or collapsed callouts.

Caution (collapsed)

This is a Callout Caution using a Paragraph Style.

Caution

This is a Callout Caution using a Paragraph Style.

Caution 1

Demonstration of a Callout Caution using the Section Type Div with class .callout-caution and with ID #cau-caution.

Important 1

Demonstration of a Callout Important using the Section Type Div with class .callout-important and with ID #imp-important.

Note 1

Demonstration of a Callout Note using the Section Type Div with class .callout-note and with ID #nte-note.

Tip 1

Demonstration of a Callout Tip using the Section Type Div with class .callout-tip and with ID #tip-tip.

Warning 2

Demonstration of a Callout Warning using the Section Type Div with class .callout-warning and with ID #wrn-warning.

5.5 Diagrams

Similarly, we can create Dot and Mermaid diagrams using Section Types (Diagram Dot, Diagram Mermaid), Paragraph Styles (Diagram Dot, Diagram Mermaid), and Raw Mardown.

Species	Markdown Source	Rendered Output
Dot	`[@fig-dot-a]`	Figure 4
Dot	`[@fig-dot-b]`	Figure 5
Dot	`[@fig-dot-c]`	Figure 6
Mermaid	`[@fig-mermaid-a]`	Figure 7
Mermaid	`[@fig-mermaid-b]`	Figure 8
Mermaid	`[@fig-mermaid-c]`	Figure 9

Table 5: Cross-referencing Dot and Mermaid diagrams.

Figure 4: Figure caption

Figure 5: A graphviz graph with figure reference and caption, using raw markup. See https://quarto.org/docs/authoring/diagrams.html#sizing for more details…

Figure 6: Color wheel diagram

flowchart
    A --> B & C & D --> E & F --> G

Figure 7: Figure caption

flowchart LR
  A{Diagram} --> B[Section Type]
  A --> C[Paragraph Style]
  A --> D[Raw Markdown]

Figure 8: Figure caption

%%{init: {"pie": {"textPosition": 0.5}, "themeVariables": {"pieOuterStrokeWidth": "5px"}} }%%
pie showData
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5

Figure 9: A Mermaid figure using a Scrivener Section Type [Computation] with class [mermaid], see https://quarto.org/docs/authoring/diagrams.html for more details

5.6 Equations

Species	Markdown Source	Rendered Output
Equation	`[@eq-demo-a]`	Equation 1
Equation	`[@eq-demo-b]`	Equation 2

Table 6: Cross-referencing equations.

\[t' = \frac{t - \dfrac{v}{c^{2}}x}{\sqrt{1 - \dfrac{v^{2}}{c^{2}}}} \tag{1}\]

\[t' = \frac{t - \dfrac{v}{c^{2}}x}{\sqrt{1 - \dfrac{v^{2}}{c^{2}}}} \tag{2}\]

5.7 Figures

Species	Markdown Source	Rendered Output
	`[@fig-ulysses]`	Figure 10
Multipart Figure	`[@fig-panel-a]`	Figure 11
Multipart Figure	`[@fig-panel-a-item-a]`	Figure 11 (a)
Multipart Figure	`[@fig-panel-a-item-b]`	Figure 11 (b)

Table 7: Cross-referencing figures.

Painting by DRAPER, 1909.

(a) Place the label first in the caption, and use the `Caption` style.

5.8 Listings

Species	Markdown Source	Rendered Output
Listing	`[@lst-demo-a]`	Listing 2
Listing	`[@lst-demo-b]`	Listing 3

Table 8: Cross-referencing listings.

require "unicode/name"

characters = %w(α β ἇ ᾇ ᾁ)

# characters = 'ἄ'
characters.each do |character|
  puts character.unpack('U*').map { |i| 
  "U+#{i.to_s(16).rjust(4, '0').upcase}"
  }.join
  puts Unicode::Name.of character
end

Listing 2: Decomposition of Unicode characters.

#!/usr/bin/env ruby
# frozen_string_literal: false

Encoding.default_external = Encoding::UTF_8

Dir["#{__dir__}/Ruby/**/*.rb"].each do |file|
  require_relative file
end

Listing 3: The caption

5.9 Tables

Species	Markdown Source	Rendered Output
	`[@tbl-demo-a]`	Table 10
	`[@tbl-demo-b]`	Table 11
Multipart Table	`[@tbl-panel-a]`	Table 12
Multipart Table	`[@tbl-panel-a-item-a]`	Table 12 (a)
Multipart Table	`[@tbl-panel-a-item-b]`	Table 12 (b)

Table 9: Cross-referencing tables.

GRC	SKT
ἐν ἀρχὴ ἦν ὁ λόγος	आदौ वाद आसीत्

Table 10: This table with a passage from John 1.1 uses the Section Type Text and Paragraph Style Table Caption.

GRC	SKT
ἐν ἀρχὴ ἦν ὁ λόγος	आदौ वाद आसीत्

Table 11: “This is an example of Section Type Table. The caption and the remaining attributes are added as part of the Section Type markup.”

Element	Prefix	Markdown Source	Rendered Output
Equation A	eq	A	B
Equation A	eq	C	D
Listing A	lst	E	F

(a) The first table of the multipart table panel.

Element	Prefix	Markdown Source	Rendered Output
Equation B	eq	A	B
Equation B	eq	C	D
Listing B	lst	E	F

(b) The second table of the multipart table panel.

Table 12: This is a markdown multi-table panel with two sub-tables generated using a Section Type Div. The Custom Metadata holds the cross-referencing label, classes, and other attributes.

5.10 Sections

Genus	Markdown Source	Rendered Output
Section	`[@sec-demo-a]`	Section 5.10.1
Break + Section	`[@sec-demo-e]`	Section 5.10.2
Heading	`[@sec-demo-c]`	Section 5.10.3
Break + Heading	`[@sec-demo-d]`	Section 5.10.4

Table 13: Note that the unnumbered section cannot be referenced.

Section (Unnumbered)

Demonstration of the Section Type Section using Class .unnumbered.

5.10.1 Section

Demonstration of the Section Type Section with ID #sec-demo-a.

5.10.2 Break + Section

Demonstration of the Section Type Break + Section with ID #sec-demo-e.

5.10.3 Heading

5.10.4 Break + Heading

6 Templates and partials

Quarto Templates optionally edited in Scrivener

Users needing control over the parameters in the native Quarto templates shouldn’t have to deal with external files. We imported all the templates and partials for the main file types (TeX, HTML, Typst) so they can be edited directly in Scrivener.

PDF

And the Pandoc sub-partials:

HTML

7 Resources

Bootstrap Icons - These are available in Quarto documents using the Shortcode Font Awesome style as in . (There is also Shortcode Env, Shortcode Meta, Shortcode Var).
The Plain Person’s Guide to Plain Text Social Science
Quarto Reference
The easiest way to publish to Github Pages
Example of Quarto Book
Quarto with GH Pages

8 Final word

If you like what you see, consider sponsoring this project on Github.

Known problems & random errors

Compilation fails for LaTeX → PDF when citations are placed in Table/Figure captions. The cause seems to be the Citation Backlinks filter.
For Typst → PDF output some Quarto features (e.g. margin notes, column classes) are not yet implemented. Hopefully this will change in future Quarto versions.

Bibliography

Primary Sources

ARISTOTELIS. “De Anima.” In: BEKKER, I. (Ed.). Aristotelis Opera. Tran.: Β. Τατάκης. Berlin: Reimer, 1834. [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]

HOMERUS. “Ilias.” In: ALLEN, T. W. (Ed.). Homeri Ilias, vols. 2–3. Oxford: Clarendon, 1931. p. 2·1-356; 3·1-370. [1]

Secondary Sources

ARISTOTELIS. De Anima. Ed.: W. Biehl. Leipzig: Teubner, 1896. [1, 2]

ARISTOTELIS. De Anima. Ed.: W. Biehl. Trans.: Willy Theiler & Horst Seidl. Harmburg: Felix Meiner, 1995. [1, 2]

LONG, C. Ethics of Ontology. Albany: SUNY, 2004. [1, 2, 3, 4, 5, 6, 7]

Workflow

HOFFMAN, D. D.; PRAKASH, C. Objects of consciousness. Frontiers in Psychology, v. 5, p. 577, 2014. [1]

Songs

MORPHINE et al. Cure For Pain. : Cure For Pain.Rykodisc, 1993. Disponível em: <https://open.spotify.com/track/3hO9gaVixKDoYDrlTBrEWf?si=0668baf1aab345d4> [1, 2, 3]

Paintings

DRAPER, H. J. Ulysses and the Sirens., 1909. [1]

Reuse

CC BY-NC-SA 4.0

Citation

BibTeX citation:

@online{untitled,
  author = {},
  title = {Hello, {ScrivQ!}},
  langid = {en}
}

For attribution, please cite this work as:

Hello, ScrivQ!

# Instalation To use ScrivQ24, you need the [Quarto](https://quarto.org/docs) open-source scientific and technical publishing system. :::{.callout-tip} ## Quickstart - On macOS^[If you're on a Mac, install Homebrew by pasting the following on the Terminal: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`.], use [Homebrew](https://brew.sh) to `brew install quarto && brew install chromium`. - On Windows, use [Chocolatey](https://chocolatey.org/) to `choco install quarto`. After that, install TinyTex with `quarto install tool tinytex`. ::: :::{.callout-tip} ## New to Quarto? - Visit the [get started](https://quarto.org/docs/get-started/) guide to download. - Check the [tutorial](https://quarto.org/docs/get-started/hello/vscode.html) to learn how to create, build, and preview documents. - Install the Quarto extension for [VS Code](https://quarto.org/docs/get-started/#quarto-for-vs-code) and [R Studio](https://quarto.org/docs/get-started/#quarto-for-rstudio). - Find out more at [Awesome Quarto](https://github.com/mcanouil/awesome-quarto), [Quarto Extensions](https://github.com/quarto-ext?type=source), [Quarto on Github](https://github.com/search?q=topic%3Aquarto&type=repositories), [RStudio Community](https://community.rstudio.com/tags/quarto), [Stack Overflow](https://stackoverflow.com/questions/tagged/quarto), [Twitter](https://twitter.com/quarto_pub). - See also the [Pandoc User's Guide](https://pandoc.org/MANUAL.html), [Pandoc-Discuss](https://github.com/jgm/pandoc/discussions), and [Pandoc at Stack Overflow](https://stackoverflow.com/questions/tagged/pandoc). ::: :::{.callout-important} ## Installation issues Run a `quarto check` on your installation. Some Python and R computations will require additional packages (cf. [@wrn-r-packages]). ::: :::{id="wrn-r-packages" .callout-warning} ## Dependencies for computations To run R computations, install [R](https://www.r-project.org), [R Studio](https://posit.co/download/rstudio-desktop/), and (*at least*) the following packages: ```{#lst-r-packages .r lst-cap="Additional R packages."} py_install(packages = "matplotlib") install.packages("reticulate") install.packages("markdown") install.packages("tidyverse") install.packages("kableExtra") install.packages("downlit") install.packages("xml2") ``` ::: # ScrivQ The ScrivQ template is designed to compile [Quarto Books](https://quarto.org/docs/books/) (PDF^[Please note that [tinytex](https://quarto.org/docs/output-formats/pdf-engine.html#installing-tex) is also required for LaTeX to PDF output.], DOCX, and HTML) with zero configuration and no dependencies on external files. The bibliography, the template files, extensions, and filters are all included in the project and will be created by the compiler script. :::{.callout-tip} ## When Quarto is installed... Hit `Cmd + Opt + E` to publish your Quarto Book right away. ::: :::{.callout-note} ## ScrivQ - **Download** the [latest release](https://github.com/bcdavasconcelos/ScrivQ/releases). - **Sponsor** [this project](https://github.com/sponsors/bcdavasconcelos). - **Take part** in the discussion at the [Scrivener forum](https://forum.literatureandlatte.com/t/scrivq-a-template-to-control-quarto-export-multiple-files-manage-bibliography-and-easily-create-cross-references/134755). ::: :::{.callout-note} ## Thank you [\@iandol](https://github.com/iandol) for the exceptional [Scrivomatic](https://github.com/iandol/scrivomatic) from which ScrivQ descended. Check his [writing in Scrivener tutorial](https://github.com/iandol/scrivomatic#writing-in-scrivener), if you haven't done so yet. ::: # Compiler Script ![There is a ruby script to reformat the text and create the dependencies. It allows you to pass a file name and a format, so you can edit the post-processing panel to change the output format (*e.g.* change `html` to `pdf` / `docx` / `epub` etc.). It is embedded in this project's Compiler format.](screencap.png){#fig-scriv-compile width="auto"} The script's output is redirected `&>` to a `Quarto.log` file that will be automatically opened when an error happens and no output is produced. If everything runs smoothly, however, you should see only the output file open. This compiler script descends from [**Scrivomatic**](https://github.com/iandol/scrivomatic), but with several changes to allow splitting the final document into sub-files. This task entails some challenges as footnotes and image references must be moved around before the file is split. Check the compiler script to see how this got solved and please report any errors. :::{.callout-warning} [Ruby](https://www.ruby-lang.org/en/downloads) must be installed on Windows machines. ::: # Citations :::{.column-margin} Μῆνιν ἄειδε, θεά, Πηληιάδεω Ἀχιλῆος ([@HomIl, I 1]) The wrath sing, goddess, of Peleus' son Achilles. ::: In ScrivQ, we use [Citeproc](https://en.wikipedia.org/wiki/CiteProc) to handle the bibliography and provide consistent output across different formats. Given Citeproc's lack of features beloved by **BibTeX** users, we included [Cite Tools](https://bcdavasconcelos.github.io/citetools) to enable multipart bibliographies, provide backlinks (see `backref` from [HyperRef](www.ctan.org/pkg/hyperref)), and access bibliographic data from sources (*author*, *editor*, *translator*, *date*, *edition*, *number*, and so on). :::{.callout-note} ## Official documentation The official documentation on citations can be found at [Pandoc](pandoc.org/MANUAL.html#citations) and [Quarto](quarto.org/docs/authoring/footnotes-and-citations.html#sec-citations). ::: :::{.callout-warning} ## Cite Tools and ScrivQ Deleting [Cite Tools](https://bcdavasconcelos.github.io/citetools) might cause the compilation to [fail]{.underline}. ::: :::{.callout-tip} ## Using **Cite Tools **in other projects `quarto install extension bcdavasconcelos/citetools`. ::: ## Basic citations 1. The citation syntax is straightforward: `@Citekey` for **Author (Date)** (an *in-text* citation); `[@Citekey]` for **Author, Date**; and `[-@Citekey]` for **Date**. 2. The citation key is optionally followed by a locator, which can be a page number, a line number, a chapter number, or a section number, preceded by a comma, *e.g.* `[@Citekey, p.10]`. 3. Multiple citations can be grouped in brackets separated by semicolons `[@CitekeyA; @CitekeyB]`. The CSL style used by Citeproc will determine the presence (or absence) of parenthesis around the rendered citation. (We favor a style that doesn't use parenthesis, but that is up to you.) | **Character Style** | **Markdown Source** | **Rendered output**^[The rendered citation will appear only in the output document; but not in the Scrivener project.] | | :-----: | :-----: | :-----: | | **Cite*** | `[-@Long2004]` | [-@Long2004] | | **Cite*** | `[-@Long2004, p.15]` | [-@Long2004, p.15] | | **Cite** | `[@Long2004]` | [@Long2004] | | **Cite** | `[@Long2004, p.15]` | [@Long2004, p.15] | Table: Citation syntax in Quarto and Pandoc. {#tbl-citations} Here is a short demonstration of the basic citation feature. We suggest grouping the citations using parenthesis and using character styles to apply the correct markup. If you were using other CSL styles, then you could drop the parenthesis. :::{.callout-note} ## (Date, locator) Long thinks [...] on the deliberations of the prudent person ([-@Long2004, p.17]). ::: :::{.callout-note} ## (Author, Date, locator) ...on the deliberations of the prudent person ([@Long2004, p.17]). ::: :::{.callout-note} ## (Author, Date, locator; Author, Date, locator) ...on the deliberations of the prudent person ([@Long2004, p.17]; [@hoffman2014, p.15]). ::: ## Citation of specific fields To inject the correct markup -- `[@Citekey]{.csl_field}` -- and allow us to cite different fields from our bibliographic entry, we rely on **Character Styles** (*e.g.* *Cite Author*, *Cite Editor*, *Cite Issued*, and so on). [Officially, [CSL has Variables](https://docs.citationstyles.org/en/stable/specification.html#appendix-iv-variables), [BibTeX has Fields](https://en.wikipedia.org/wiki/BibTeX#Field_types), and [RIS has Tags](https://en.wikipedia.org/wiki/RIS_(file_format)#Tags), but we stuck to the term fields to describe all of them.]{.aside} | Character Style | Markdown Source | Rendered Output | | :-----: | :-----: | :-----: | | Cite Author | `[@DA]{.author}` | [@DA]{.author} | | Cite Editor | `[@DA]{.editor}` | [@DA]{.editor} | | Cite Translator | `[@DA]{.translator}` | [@DA]{.translator} | | Cite Issued | `[@DA]{.issued}` | [@DA]{.issued} | | Cite Title | `[@DA]{.title}` | [@DA]{.title} | | Cite Title-short | `[@DA]{.title-short}` | [@DA]{.title-short} | | Cite Original-title | `[@DA]{.original-title}` | [@DA]{.original-title} | | Cite Publisher | `[@DA]{.publisher}` | [@DA]{.publisher} | | Cite Publisher-Place | `[@DA]{.publisher-place}` | [@DA]{.publisher-place} | Table: All ready-made **Character Styles** for the Cite Field lua filter. {#tbl-cite-field} :::{.callout-note} ## An example with field citation [@DA]{.editor} published the first modern edition of Aristotle's [@DA]{.original-title} ([@DA]{.title}) in [@DA]{.issued}. A new edition by [@DABiehl]{.editor} appeared in [@DABiehl]{.issued} (later reprinted in [@DATheiler]{.translator}'s [@DATheiler]{.issued} translation). ::: ## Multipart Bibliography :::{.callout-tip} ## Where do I plug my bibliography? There is no need to keep **separate bibliography files** in the system. Simply **copy and paste the references directly to Scrivener** following the instructions below. ::: :::{.callout-tip} ## References format **Pandoc** and **Quarto** use a [CSL](https://docs.citationstyles.org/en/stable/specification.html) (*Citation Style Language*) engine and prefer [CSL-YAML and CSL-JSON](https://docs.citationstyles.org/en/stable/specification.html) (performing up to 10x faster) over [BibTeX](https://en.wikipedia.org/wiki/BibTeX#Entry_types) and [RIS](https://en.wikipedia.org/wiki/RIS_(file_format)#Type_of_reference), which need to be converted before they can be understood. ::: :::{.callout-tip} ## What if I don't have a bibliography ready? - Check [Zotero](www.zotero.org)^[Zotero even offers an API to download shared libraries by merely accessing a link, such as `https://api.zotero.org/groups/`LibraryID`/items?format=bibtex&limit=999` where `LibraryID` corresponds to the library's 7-digit code (visible in the middle of the library URL).] and [JabRef](www.jabref.org) on all platforms. - On macOS, check [Bookends](www.sonnysoftware.com/) and [Bibdesk](bibdesk.sourceforge.io); - See also [this comparison](en.wikipedia.org/wiki/Comparison_of_reference_management_software). ::: [BibTeX]: [CSL]: https://docs.citationstyles.org/en/stable/specification.html#appendix-iii-types [CSL-YAML]: https://docs.citationstyles.org/en/stable/specification.html [CSL-JSON]: https://docs.citationstyles.org/en/stable/specification.html [RIS]: https://en.wikipedia.org/wiki/RIS_(file_format)#Type_of_reference ### How to manually create a multipart bibliography {id="nte-multibib1" .callout-note} 1. Using the **Section Type** `File`, we create a representation of our bibliography file to add the data (*e.g.* [Primary Sources](refs/primary-sources.yml) and [Secondary Sources](refs/secondary-sources.yml)). 2. On the Metadata panel we set the relative path (`ID-Prefix` + `ID`) and the extension (`Extension`) of the actual bibliography file that will be created upon **Compile**. ![The Metadata panel](BibliographyFile.png){#fig-bibliography width="auto"} 3. We need to tell Quarto about the bibliography file by adding it to the [_quarto](_quarto.yml) configuration file (there is a bibliography section), then we can print the formatted bibliography using the ID (*e.g.* "primary-sources") with the **Paragraph Style** *Div Bibliography*. ::: {#refs_primary-sources} ::: ### How to automatically create a multipart bibliography {id="nte-multibib2" .callout-note} We can use the **Section Type** Bibliography to automate steps 3 and 4. This is very convenient for books that need the bibliography to print only once at the very end. 1. Using the **Section Type** `File`, we create a representation of our bibliography file to add the data (*e.g.* [Primary Sources](refs/primary-sources.yml) and [Secondary Sources](refs/secondary-sources.yml)). 2. On the Metadata panel we set the relative path (`ID-Prefix` + `ID`) and the extension (`Extension`) of the actual bibliography file that will be created upon **Compile**. 3. The metadata with the file path will be automatically added and the formatted bibliography will be printed in the same section as the data, with the same section title. ## Backlinks In Citeproc, `link-citations` control whether citations in the body of the text should be clickable links to the reference in the bibliography. **Cite Tools** takes it further and adds a backlink to each citation an entry has received in the document in a crescent ordinal fashion^[The reader will see the page number instead of a crescent ordinal number in some output formats, such as PDF.]. This allows the reader to easily arrive at sections of the text where the same reference was discussed and quickly see how many times each reference was used with the array of backlinks. ![The **Citation Backlinks** filter adds an index of cited references to the bibliography, with links back to all in-text citations. It also allows the user to turn these off globally or in an *ad hoc* fashion.](backrefs.png){#fig-scrivlinkC width="auto"} :::{.callout-tip} ## Citing specific fields Turn `link-fields` into false to avoid undesired linking ::: :::{.callout-note} ## Bibliography links - [link-citations]{.underline}: Hyperlink citations to the corresponding bibliography entries. Defaults to true. - [link-fields]{.underline}: Hyperlink citations targeting specific CSL fields to the corresponding entries in the bibliography. Defaults to true. - [link-bibliography]{.underline}: Hyperlink DOIs, PMCIDs, PMID, and URLs in bibliographies. Defaults to true. - [lang]{.underline}: Affects the bibliography tags. Defaults to `en-US`. ::: # Quarto :::{.column-margin} "I propose a toast, to my self-control. You see it helpless, crawling on the floor." [@MorphineCFP]{.author}, [@MorphineCFP]{.title} ([-@MorphineCFP]) ::: ## Scrivener Project Templates All sorts of internal **Scrivener Templates** have been included for convenience. They serve as starting points to create new sections. Click **Project > New From Template** and select the desired **Section Types** from the list, which includes `Bibliography`, `Code`, `Computation`, `Diagram Dot`, `Diagram Mermaid`, `Div`, `Equation`, `File`, `Metadata`, `Section`, `Text`, `Text (Anchored)`^[Text section with ID for cross-referencing.]. This provides a huge number of options as the metadata can be edited to allow the creation of different **Quarto** elements and their customization (*e.g.* using classes and attributes). Using the **Section Type** `Div`, for example, one could create 8 different **Amsthm** elements, 5 different **Callouts**, and several **Column** environments. Using the `Computation`, one can create executable code blocks with R, Python, and Ruby. The **Section Type** `Section` can be numbered, unnumbered, or part of the appendix (with the use of classes). Look at the ready-made examples to see what else is possible. ## Cross-referencing When creating a **Section**, select the correct `ID-Prefix` (*e.g.* `sec-`) and fill the `ID` metadata field with a value (*e.g.* `xref`). Then, **use Scrivener placeholders** ( `<\$Custom:ID-Prefix><\$Custom:ID>`) with a link to the cited element, so that this gets replaced with `sec-xref`. This works regardless of the element being cross-referenced (*e.g.* *section*, *table*, *figure*, *listing*) because this strategy ensures the citation will use the `<\$Custom:ID-Prefix>` pulled from the targeted element (*e.g.* `sec-`, `tbl-`, `fig-`, `lst-`), making it compatible with all element types. :::{.callout-warning} ## Alternative to placeholders A less verbose option uses a replacement rule: - `s\crivlink` is replaced with `<\$Custom:ID-Prefix><\$Custom:ID>`. - `s\crivpath` and `$\!` are replaced with `<\$Custom:ID-Prefix><\$Custom:ID><\$Custom:Extension>`. ::: :::{.callout-tip} ## How to cross-reference an element 1. Type [your-keyword-of-choice]{.underline} or `s\crivlink`; 2. Apply the **Character Style** *Cite* (**hit** `Shift + Command + Y`) 3. Link to the document that contains the element (**hit** [Command + L]{.underline}). ::: :::{.callout-caution} ## Known limitation Understand that **Scrivener Placeholders** can only pull information from the section properties, so the generic link label (*e.g.* `s\crivlink`) will work to reference elements created from **Section Types**. To reference elements created from **Raw Markup** or **Character Style**, use the actual `ID` given (*e.g.* `fig-ulysses`). ::: ## Amsthm | **Species** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | | Conjecture | `[@cnj-demo]` | [@cnj-demo] | | Corollary | `[@cor-demo]` | [@cor-demo] | | Definition | `[@def-demo]` | [@def-demo] | | Example | `[@exm-demo]` | [@exm-demo] | | Exercise | `[@exr-demo]` | [@exr-demo] | | Lemma | `[@lem-demo]` | [@lem-demo] | | Proposition | `[@prp-demo]` | [@prp-demo] | | Theorem | `[@thm-demo]` | [@thm-demo] | Table: Cross-referencing **Amsthm** elements in ScrivQ. {#tbl-amsthm} :::{id="cnj-demo"} Demonstration of the **Conjecture** theorem environment using the **Section Type** `Div` with **ID** `#cnj-demo`. ::: :::{id="cor-demo"} Demonstration of the **Corollary** theorem environment using the **Section Type** `Div` with **ID** `#cor-demo`. ::: :::{id="def-demo"} Demonstration of the **Definition** theorem environment using the **Section Type** `Div` with **ID** `#def-demo`. ::: :::{id="exm-demo"} Demonstration of the **Example** theorem environment using the **Section Type** `Div` with **ID** `#exm-demo`. ::: :::{id="exr-demo"} Demonstration of the **Exercise** theorem environment using the **Section Type** `Div` with **ID** `#exr-demo`. ::: :::{id="lem-demo"} Demonstration of the **Lemma** theorem environment using the **Section Type** `Div` with **ID** `#lem-demo`. ::: :::{id="prp-demo"} Demonstration of the **Proposition** theorem environment using the **Section Type** `Div` with **ID** `#prp-demo`. ::: :::{id="thm-demo"} Demonstration of the **Theorem** theorem environment using the **Section Type** `Div` with **ID** `#thm-demo`. $$[ x^2 + y^2 = z^2 ]$$ ::: ## Callouts | **Species** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | | Caution | `[@cau-caution]` | [@cau-caution] | | Important | `[@imp-important]` | [@imp-important] | | Note | `[@nte-note]` | [@nte-note] | | Tip | `[@tip-tip]` | [@tip-tip] | | Warning | `[@wrn-warning]` | [@wrn-warning] | Table: Cross-referencing callouts. {#tbl-callouts} Using styles, you can create normal or collapsed callouts. :::{.callout-caution collapse="true"} ## Caution (collapsed) This is a Callout Caution using a **Paragraph Style**. ::: :::{.callout-caution} ## Caution This is a Callout Caution using a **Paragraph Style**. ::: :::{id="cau-caution" .callout-caution appearance="simple"} Demonstration of a **Callout Caution** using the **Section Type** `Div` with class `.callout-caution` and with **ID** `#cau-caution`. ::: :::{id="imp-important" .callout-important appearance="simple"} Demonstration of a **Callout Important** using the **Section Type** `Div` with class `.callout-important` and with **ID** `#imp-important`. ::: :::{id="nte-note" .callout-note appearance="simple"} Demonstration of a **Callout Note** using the **Section Type** `Div` with class `.callout-note` and with **ID** `#nte-note`. ::: :::{id="tip-tip" .callout-tip appearance="simple"} Demonstration of a **Callout Tip** using the **Section Type** `Div` with class `.callout-tip` and with **ID** `#tip-tip`. ::: :::{id="wrn-warning" .callout-warning appearance="simple"} Demonstration of a **Callout Warning** using the **Section Type** `Div` with class `.callout-warning` and with **ID** `#wrn-warning`. ::: ## Diagrams Similarly, we can create **Dot** and **Mermaid** diagrams using **Section Types** (*Diagram Dot*, *Diagram Mermaid*), **Paragraph Styles** (*Diagram Dot*, *Diagram Mermaid*), and **Raw Mardown**. | **Species** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | | Dot | `[@fig-dot-a]` | [@fig-dot-a] | | Dot | `[@fig-dot-b]` | [@fig-dot-b] | | Dot | `[@fig-dot-c]` | [@fig-dot-c] | | Mermaid | `[@fig-mermaid-a]` | [@fig-mermaid-a] | | Mermaid | `[@fig-mermaid-b]` | [@fig-mermaid-b] | | Mermaid | `[@fig-mermaid-c]` | [@fig-mermaid-c] | Table: Cross-referencing **Dot** and **Mermaid** diagrams. {#tbl-diagrams} ```{dot} //| label: fig-dot-a //| fig-cap: Figure caption //| column: page-right //| echo: false digraph finite_state_machine { Fontname="Avenir,Helvetica,sans-serif" node [fontname="Avenir,Helvetica,sans-serif"] edge [fontname="Avenir,Helvetica,sans-serif"] rankdir=LR; node [shape = doublecircle]; 0 3 4 8; node [shape = circle]; 0 -> 2 [label = "SS(B)"]; 0 -> 1 [label = "SS(S)"]; 1 -> 3 [label = "S($end)"]; 2 -> 6 [label = "SS(b)"]; 2 -> 5 [label = "SS(a)"]; 2 -> 4 [label = "S(A)"]; 5 -> 7 [label = "S(b)"]; 5 -> 5 [label = "S(a)"]; 6 -> 6 [label = "S(b)"]; 6 -> 5 [label = "S(a)"]; 7 -> 8 [label = "S(b)"]; 7 -> 5 [label = "S(a)"]; 8 -> 6 [label = "S(b)"]; 8 -> 5 [label = "S(a)"]; } ``` ```{dot} //| label: fig-dot-b //| fig-cap: "A graphviz graph with figure reference and caption, using raw markup. See https://quarto.org/docs/authoring/diagrams.html#sizing for more details..." //| column: page-right //| echo: false digraph regexp { fontname="Helvetica,Arial,sans-serif" node [fontname="Helvetica,Arial,sans-serif"] edge [fontname="Helvetica,Arial,sans-serif"] n0 [label="regexp", URL="https://godoc.org/regexp", tooltip="Package regexp implements regular expression search."]; n1 [label="bytes", URL="https://godoc.org/bytes", tooltip="Package bytes implements functions for the manipulation of byte slices."]; n2 [label="io", URL="https://godoc.org/io", tooltip="Package io provides basic interfaces to I/O primitives."]; n3 [label="regexp/syntax", URL="https://godoc.org/regexp/syntax", tooltip="Package syntax parses regular expressions into parse trees and compiles parse trees into programs."]; n4 [label="sort", URL="https://godoc.org/sort", tooltip="Package sort provides primitives for sorting slices and user-defined collections."]; n5 [label="strconv", URL="https://godoc.org/strconv", tooltip="Package strconv implements conversions to and from string representations of basic data types."]; n6 [label="strings", URL="https://godoc.org/strings", tooltip="Package strings implements simple functions to manipulate UTF-8 encoded strings."]; n7 [label="sync", URL="https://godoc.org/sync", tooltip="Package sync provides basic synchronization primitives such as mutual exclusion locks."]; n8 [label="unicode", URL="https://godoc.org/unicode", tooltip="Package unicode provides data and functions to test some properties of Unicode code points."]; n9 [label="unicode/utf8", URL="https://godoc.org/unicode/utf8", tooltip="Package utf8 implements functions and constants to support text encoded in UTF-8."]; n10 [label="internal/bytealg", URL="https://godoc.org/internal/bytealg", tooltip=""]; n11 [label="errors", URL="https://godoc.org/errors", tooltip="Package errors implements functions to manipulate errors."]; n12 [label="internal/reflectlite", URL="https://godoc.org/internal/reflectlite", tooltip="Package reflectlite implements lightweight version of reflect, not using any package except for \"runtime\" and \"unsafe\"."]; n13 [label="math", URL="https://godoc.org/math", tooltip="Package math provides basic constants and mathematical functions."]; n14 [label="math/bits", URL="https://godoc.org/math/bits", tooltip="Package bits implements bit counting and manipulation functions for the predeclared unsigned integer types."]; n15 [label="unsafe", URL="https://godoc.org/unsafe", tooltip="Package unsafe contains operations that step around the type safety of Go programs."]; n16 [label="internal/race", URL="https://godoc.org/internal/race", tooltip="Package race contains helper functions for manually instrumenting code for the race detector."]; n17 [label="runtime", URL="https://godoc.org/runtime", tooltip=""]; n18 [label="sync/atomic", URL="https://godoc.org/sync/atomic", tooltip="Package atomic provides low-level atomic memory primitives useful for implementing synchronization algorithms."]; n19 [label="internal/cpu", URL="https://godoc.org/internal/cpu", tooltip="Package cpu implements processor feature detection used by the Go standard library."]; n0 -> n1; n0 -> n2; n0 -> n3; n0 -> n4; n0 -> n5; n0 -> n6; n0 -> n7; n0 -> n8; n0 -> n9; n1 -> n10; n1 -> n2; n1 -> n8; n1 -> n9; n1 -> n11; n2 -> n11; n2 -> n7; n3 -> n4; n3 -> n5; n3 -> n6; n3 -> n8; n3 -> n9; n4 -> n12; n5 -> n10; n5 -> n13; n5 -> n9; n5 -> n11; n5 -> n14; n6 -> n2; n6 -> n7; n6 -> n15; n6 -> n11; n6 -> n10; n6 -> n8; n6 -> n9; n7 -> n16; n7 -> n17; n7 -> n18; n7 -> n15; n10 -> n19; n10 -> n15; n11 -> n12; n12 -> n17; n12 -> n15; n13 -> n15; n13 -> n19; n13 -> n14; n14 -> n15; n16 -> n15; n18 -> n15; } ``` ```{dot} //| label: fig-dot-c //| fig-cap: "Color wheel diagram" //| //| column: page-right graph Color_wheel { graph [ layout = neato label = "Color wheel, 33 colors.\nNeato layout" labelloc = b fontname = "Helvetica,Arial,sans-serif" start = regular normalize = 0 ] node [ shape = circle style = filled color = "#00000088" fontname = "Helvetica,Arial,sans-serif" ] edge [ len = 2.7 color = "#00000088" fontname = "Helvetica,Arial,sans-serif" ] subgraph Dark { node [fontcolor = white width = 1.4] center [width = 1 style = invis shape = point] center -- darkred [label = "0°/360°"] darkred [fillcolor = darkred] brown [fillcolor = brown] brown -- center [label = "30°"] olive [fillcolor = olive] olive -- center [label = "60°"] darkolivegreen [fillcolor = darkolivegreen fontsize = 10] darkolivegreen -- center [label = "90°"] darkgreen [fillcolor = darkgreen] darkgreen -- center [label = "120°"] "dark hue 0.416" [color = ".416 1 .6" fontcolor = white] "dark hue 0.416" -- center [label = "150°"] darkcyan [fillcolor = darkcyan] darkcyan -- center [label = "180°"] "dark hue 0.583" [color = ".583 1 .6" fontcolor = white] "dark hue 0.583" -- center [label = "210°"] darkblue [fillcolor = darkblue] darkblue -- center [label = "240°"] "dark hue 0.750" [color = ".750 1 .6"] "dark hue 0.750" -- center [label = "270°"] darkmagenta [fillcolor = darkmagenta] darkmagenta -- center [label = "300°"] "dark hue 0.916" [color = ".916 1 .6"] "dark hue 0.916" -- center [label = "330°"] } subgraph Tue { node [width = 1.3] "hue 0.083" -- brown "hue 0.083" [color = ".083 1 1"] "hue 0.125" [color = ".125 1 1"] "hue 0.166" -- olive "hue 0.166" [color = ".166 1 1"] "hue 0.208" [color = ".208 1 1"] "hue 0.250" -- darkolivegreen "hue 0.250" [color = ".250 1 1"] "hue 0.291" [color = ".291 1 1"] "hue 0.333" -- darkgreen "hue 0.333" [color = ".333 1 1"] "hue 0.375" [color = ".375 1 1"] "hue 0.416" -- "dark hue 0.416" "hue 0.416" [color = ".416 1 1"] "hue 0.458" [color = ".458 1 1"] "hue 0.500" -- darkcyan "hue 0.500" [color = ".500 1 1"] "hue 0.541" [color = ".541 1 1"] node [fontcolor = white] "hue 0.000" [color = ".000 1 1"] "hue 0.000" -- darkred "hue 0.041" [color = ".041 1 1"] "hue 0.583" -- "dark hue 0.583" "hue 0.583" [color = ".583 1 1"] "hue 0.625" [color = ".625 1 1"] "hue 0.666" -- darkblue "hue 0.666" [color = ".666 1 1"] "hue 0.708" [color = ".708 1 1"] "hue 0.750" -- "dark hue 0.750" "hue 0.750" [color = ".750 1 1"] "hue 0.791" [color = ".791 1 1"] "hue 0.833" -- darkmagenta "hue 0.833" [color = ".833 1 1"] "hue 0.875" [color = ".875 1 1"] "hue 0.916" -- "dark hue 0.916" "hue 0.916" [color = ".916 1 1"] "hue 0.958" [color = ".958 1 1"] edge [len = 1] "hue 0.000" -- "hue 0.041" -- "hue 0.083" -- "hue 0.125" -- "hue 0.166" -- "hue 0.208" "hue 0.208" -- "hue 0.250" -- "hue 0.291" -- "hue 0.333" -- "hue 0.375" -- "hue 0.416" "hue 0.416" -- "hue 0.458" -- "hue 0.500" --"hue 0.541" -- "hue 0.583" -- "hue 0.625" "hue 0.625" -- "hue 0.666" -- "hue 0.708" -- "hue 0.750" -- "hue 0.791" -- "hue 0.833" "hue 0.833" -- "hue 0.875" -- "hue 0.916" -- "hue 0.958" -- "hue 0.000" } subgraph Main_colors { node [width = 2 fontsize = 20] red [fillcolor = red fontcolor = white] orangered [fillcolor = orangered] orange [fillcolor = orange] gold [fillcolor = gold] yellow [fillcolor = yellow] yellowgreen [fillcolor = yellowgreen] deeppink [fillcolor = deeppink fontcolor = white] fuchsia [label = "fuchsia\nmagenta" fillcolor = fuchsia fontcolor = white] purple [fillcolor = purple fontcolor = white] blue [fillcolor = blue fontcolor = white] cornflowerblue [fillcolor = cornflowerblue] deepskyblue [fillcolor = deepskyblue] aqua [fillcolor = aqua label = "aqua\ncyan"] springgreen [fillcolor = springgreen] green [fillcolor = green] purple -- fuchsia -- deeppink -- red cornflowerblue -- blue -- purple cornflowerblue -- deepskyblue -- aqua [len = 1.7] aqua -- springgreen -- green -- yellowgreen -- yellow yellow -- gold -- orange -- orangered -- red [len = 1.6] orange -- "hue 0.083" deeppink -- "hue 0.916" deeppink -- "hue 0.875" red -- "hue 0.000" yellowgreen -- "hue 0.250" blue -- "hue 0.666" yellow -- "hue 0.166" gold -- "hue 0.125" green -- "hue 0.333" springgreen -- "hue 0.416" aqua -- "hue 0.500" cornflowerblue -- "hue 0.583" deepskyblue -- "hue 0.541" purple -- "hue 0.791" purple -- "hue 0.750" fuchsia -- "hue 0.833" } subgraph Light_colors { node [width = 2 fontsize = 20] node [shape = circle width = 1.8] edge [len = 2.1] pink [fillcolor = pink] pink -- red lightyellow [fillcolor = lightyellow] lightyellow -- yellow mediumpurple [fillcolor = mediumpurple] mediumpurple -- purple violet [fillcolor = violet] violet -- fuchsia hotpink [fillcolor = hotpink] hotpink -- deeppink "light hue 0.250" [color = ".250 .2 1"] "light hue 0.250" -- yellowgreen lightcyan [fillcolor = lightcyan] lightcyan -- aqua lightslateblue [fillcolor = lightslateblue] lightslateblue -- blue lightgreen [fillcolor = lightgreen] lightgreen -- green lightskyblue [fillcolor = lightskyblue] lightskyblue -- deepskyblue peachpuff [fillcolor = peachpuff] peachpuff -- orange "light hue 0.416" [color = ".416 .2 1"] "light hue 0.416" -- springgreen } subgraph Tints { node [width = 1] edge [len = 2.4] "hue 0 tint" -- pink "hue 0 tint" [color = "0 .1 1"] "hue 0.041 tint" [color = ".041 .1 1"] "hue 0.083 tint" -- peachpuff "hue 0.083 tint" [color = ".083 .1 1"] "hue 0.125 tint" [color = ".125 .1 1"] "hue 0.166 tint" -- lightyellow "hue 0.166 tint" [color = ".166 .1 1"] "hue 0.208 tint" [color = ".208 .1 1"] "hue 0.250 tint" -- "light hue 0.250" "hue 0.250 tint" [color = ".250 .1 1"] "hue 0.291 tint" [color = ".291 .1 1"] "hue 0.333 tint" -- lightgreen "hue 0.333 tint" [color = ".333 .1 1"] "hue 0.375 tint" [color = ".375 .1 1"] "hue 0.416 tint" -- "light hue 0.416" "hue 0.416 tint" [color = ".416 .1 1"] "hue 0.458 tint" [color = ".458 .1 1"] "hue 0.5 tint" -- lightcyan "hue 0.5 tint" [color = ".5 .1 1"] "hue 0.541 tint" -- lightskyblue "hue 0.541 tint" [color = ".541 .1 1"] "hue 0.583 tint" [color = ".583 .1 1"] "hue 0.625 tint" [color = ".625 .1 1"] "hue 0.666 tint" -- lightslateblue "hue 0.666 tint" [color = ".666 .1 1"] "hue 0.708 tint" [color = ".708 .1 1"] "hue 0.750 tint" -- mediumpurple "hue 0.750 tint" [color = ".750 .1 1"] "hue 0.791 tint" [color = ".791 .1 1"] "hue 0.833 tint" -- violet "hue 0.833 tint" [color = ".833 .1 1"] "hue 0.875 tint" [color = ".875 .1 1"] "hue 0.916 tint" -- hotpink "hue 0.916 tint" [color = ".916 .1 1"] "hue 0.958 tint" [color = ".958 .1 1"] edge [len = 2] "hue 0 tint" -- "hue 0.041 tint" -- "hue 0.083 tint" -- "hue 0.125 tint" -- "hue 0.166 tint" -- "hue 0.208 tint" "hue 0.208 tint" -- "hue 0.250 tint" -- "hue 0.291 tint" -- "hue 0.333 tint" -- "hue 0.375 tint" -- "hue 0.416 tint" "hue 0.416 tint" -- "hue 0.458 tint" -- "hue 0.5 tint" --"hue 0.541 tint" -- "hue 0.583 tint" -- "hue 0.625 tint" "hue 0.625 tint" -- "hue 0.666 tint" -- "hue 0.708 tint" -- "hue 0.750 tint" -- "hue 0.791 tint" -- "hue 0.833 tint" "hue 0.833 tint" -- "hue 0.875 tint" -- "hue 0.916 tint" -- "hue 0.958 tint" -- "hue 0 tint" } // © 2022 Costa Shulyupin, licensed under EPL } ``` ```{mermaid} %%| label: fig-mermaid-a %%| fig-cap: Figure caption flowchart A --> B & C & D --> E & F --> G ``` ```{mermaid} %%| label: fig-mermaid-b %%| fig-cap: Figure caption %%| column: page-right %%| echo: false flowchart LR A{Diagram} --> B[Section Type] A --> C[Paragraph Style] A --> D[Raw Markdown] ``` ```{mermaid} %%| label: fig-mermaid-c %%| fig-cap: "A Mermaid figure using a Scrivener Section Type [Computation] with class [mermaid], see https://quarto.org/docs/authoring/diagrams.html for more details" %%| %%| %%{init: {"pie": {"textPosition": 0.5}, "themeVariables": {"pieOuterStrokeWidth": "5px"}} }%% pie showData title Key elements in Product X "Calcium" : 42.96 "Potassium" : 50.05 "Magnesium" : 10.01 "Iron" : 5 ``` ## Equations | **Species** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | | Equation | `[@eq-demo-a]` | [@eq-demo-a] | | Equation | `[@eq-demo-b]` | [@eq-demo-b] | Table: Cross-referencing **equations**. {#tbl-equations} $$t' = \frac{t - \dfrac{v}{c^{2}}x}{\sqrt{1 - \dfrac{v^{2}}{c^{2}}}}$$ {#eq-demo-a} $$t' = \frac{t - \dfrac{v}{c^{2}}x}{\sqrt{1 - \dfrac{v^{2}}{c^{2}}}} $${#eq-demo-b} ## Figures | **Species** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | | | `[@fig-ulysses]` | [@fig-ulysses] | | Multipart Figure | `[@fig-panel-a]` | [@fig-panel-a] | | Multipart Figure | `[@fig-panel-a-item-a]` | [@fig-panel-a-item-a] | | Multipart Figure | `[@fig-panel-a-item-b]` | [@fig-panel-a-item-b] | Table: Cross-referencing figures. {#tbl-figures} ![Ulysses and the Sirens.](Ulysses-sirens.jpg){#fig-ulysses width="auto"} Painting by [@Draper1909]. :::{id="fig-panel-a" .column-page layout-ncol=2 layout-valign="bottom"} ![Place the label first in the caption, and use the `Caption` style.](Elephant2.jpg){#fig-panel-a-item-a width="auto"} ![Angry elephant with a big trunk.](Elephant3.jpg){#fig-panel-a-item-b width="auto"} This multi-figure panel uses the **Section Type** `Div` instead of raw markdown as shown here. `ID`, `Class`, and `Attributes` specific to the block are saved to `Custom Metadata → ID, Class & Attributes`, and then inserted into the markup for this chunk by the Section Layout at compile time. ::: ## Listings | **Species** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | | Listing | `[@lst-demo-a]` | [@lst-demo-a] | | Listing | `[@lst-demo-b]` | [@lst-demo-b] | Table: Cross-referencing listings. {#tbl-listings} ```{#lst-demo-a lst-cap="Decomposition of Unicode characters." .ruby} require "unicode/name" characters = %w(α β ἇ ᾇ ᾁ) # characters = 'ἄ' characters.each do |character| puts character.unpack('U*').map { |i| "U+#{i.to_s(16).rjust(4, '0').upcase}" }.join puts Unicode::Name.of character end ``` ```{id="lst-demo-b" lst-cap="The caption" .ruby .numberLines startFrom="1"} #!/usr/bin/env ruby # frozen_string_literal: false Encoding.default_external = Encoding::UTF_8 Dir["#{__dir__}/Ruby/**/*.rb"].each do |file| require_relative file end ``` ## Tables | **Species** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | | | `[@tbl-demo-a]` | [@tbl-demo-a] | | | `[@tbl-demo-b]` | [@tbl-demo-b] | | Multipart Table | `[@tbl-panel-a]` | [@tbl-panel-a] | | Multipart Table | `[@tbl-panel-a-item-a]` | [@tbl-panel-a-item-a] | | Multipart Table | `[@tbl-panel-a-item-b]` | [@tbl-panel-a-item-b] | Table: Cross-referencing tables. {#tbl-tables} | **GRC** | **SKT** | | :-----: | :-----: | | [ἐν ἀρχὴ ἦν ὁ λόγος]{lang=grc} | [आदौ वाद आसीत्]{lang=sa} | Table: This table with a passage from John 1.1 uses the **Section Type** [Text]{.underline} and **Paragraph Style** [Table Caption]{.underline}. {#tbl-demo-a} | **GRC** | **SKT** | | :-----: | :-----: | | [ἐν ἀρχὴ ἦν ὁ λόγος]{lang=grc} | [आदौ वाद आसीत्]{lang=sa} | : "This is an example of **Section Type** `Table`. The caption and the remaining attributes are added as part of the Section Type markup." {#tbl-demo-b} :::{id="tbl-panel-a" layout-ncol=1} | **Element** | **Prefix** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | :-----: | | Equation A | eq | A | B | | Equation A | eq | C | D | | Listing A | lst | E | F | Table: The first table of the multipart table panel. {#tbl-panel-a-item-a} | **Element** | **Prefix** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | :-----: | | Equation B | eq | A | B | | Equation B | eq | C | D | | Listing B | lst | E | F | Table: The second table of the multipart table panel. {#tbl-panel-a-item-b} This is a markdown multi-table panel with two sub-tables generated using a **Section Type** `Div`. The **Custom Metadata** holds the cross-referencing label, classes, and other attributes. ::: ## Sections {id="sec-dem"} | **Genus** | **Markdown Source** | **Rendered Output** | | :-----: | :-----: | :-----: | | Section | `[@sec-demo-a]` | [@sec-demo-a] | | Break + Section | `[@sec-demo-e]` | [@sec-demo-e] | | Heading | `[@sec-demo-c]` | [@sec-demo-c] | | Break + Heading | `[@sec-demo-d]` | [@sec-demo-d] | Table: Note that the unnumbered section cannot be referenced. {#tbl-sections} ### Section (Unnumbered) {id="sec-demo-b" .unnumbered} Demonstration of the **Section Type** *Section* using **Class** `.unnumbered`. ### Section {id="sec-demo-a"} Demonstration of the **Section Type** *Section* with **ID** `#sec-demo-a`. {{< pagebreak >}} ### Break + Section {id="sec-demo-e"} Demonstration of the **Section Type** *Break + Section* with **ID** `#sec-demo-e`. ### Heading {id="sec-demo-c"} --- ### Break + Heading {id="sec-demo-d"} # Templates and partials :::{.callout-caution} ## **Quarto** Templates optionally edited in **Scrivener** Users needing control over the parameters in the native **Quarto** templates shouldn't have to deal with external files. We imported all the templates and partials for the main file types (TeX, HTML, Typst) so they can be edited directly in Scrivener. ::: :::{.callout-note collapse="true"} ## PDF - [doc-class](_extensions/templates/tex/doc-class.tex) - [title](_extensions/templates/tex/title.tex) - [toc](_extensions/templates/tex/toc.tex) - [before-body](_extensions/templates/tex/before-body.tex) - [before-bib](_extensions/templates/tex/before-bib.tex) - [biblio](_extensions/templates/tex/biblio.tex) - [after-body](_extensions/templates/tex/after-body.tex) And the Pandoc sub-partials: - [tightlist](_extensions/templates/tex/tightlist.tex) - [tables](_extensions/templates/tex/tables.tex) - [graphics](_extensions/templates/tex/graphics.tex) - [citations](_extensions/templates/tex/citations.tex) ::: :::{.callout-note collapse="true"} ## HTML - [title-block](_extensions/templates/html/title-block.html) - [styles](_extensions/templates/html/styles.html) - [html-template](_extensions/templates/html/html.template) - [html-styles](_extensions/templates/html/html.styles) - [toc](_extensions/templates/html/toc.html) - [metadata](_extensions/templates/html/metadata.html) ::: # Resources - [Bootstrap Icons](https://icons.getbootstrap.com) - These are available in Quarto documents using the **Shortcode Font Awesome** style as in `{{< fa regular bell >}}` {{< fa regular bell >}}. (There is also **Shortcode Env**, **Shortcode Meta**, **Shortcode Var**). - [The Plain Person's Guide to Plain Text Social Science](https://plain-text.co/index.html#introduction) - [Quarto Reference](https://quarto.org/docs/reference/) - The easiest way to [publish to Github Pages](quarto.org/docs/publishing/github-pages.html#render-to-docs) - [Example of Quarto Book](https://github.com/jjallaire/hopr/blob/master/_quarto.yml) - [Quarto with GH Pages](https://tarleb.com/posts/quarto-with-gh-pages/) # Final word If you like what you see, consider sponsoring [this project on Github](https://github.com/sponsors/bcdavasconcelos). :::{.callout-warning collapse="true"} ## Known problems & random errors - Compilation fails for **LaTeX → PDF** when citations are placed in Table/Figure captions. The cause seems to be the **Citation Backlinks** filter. - For **Typst → PDF** output some **Quarto** features (*e.g.* margin notes, column classes) are not yet implemented. Hopefully this will change in future Quarto versions. ::: # Bibliography {.unnumbered} ## Primary Sources {#sec-primary-sources .unnumbered} --- bibliography_primary-sources: "refs/primary-sources.yml" --- ::: {#refs_primary-sources} ::: ## Secondary Sources {#sec-secondary-sources .unnumbered} --- bibliography_secondary-sources: "refs/secondary-sources.yml" --- ::: {#refs_secondary-sources} ::: ## Workflow {#sec-workflow .unnumbered} --- bibliography_workflow: "refs/workflow.bib" --- ::: {#refs_workflow} ::: ## Songs {#sec-songs .unnumbered} --- bibliography_songs: "refs/songs.yml" --- ::: {#refs_songs} ::: ## Paintings {#sec-paintings .unnumbered} --- bibliography_paintings: "refs/paintings.yml" --- ::: {#refs_paintings} :::